home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / cawf2st.zoo / 00readme next >
Text File  |  1991-06-04  |  7KB  |  178 lines
  1. Cawf - nroff-like text formatter
  2.  
  3. Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text)
  4. Formatter.  (Awf is written in awk and appears in comp.sources.unix,
  5. Volume 23, Issue 27.)  Cawf and awf provide a usable subset of raw nroff
  6. capabilities and the styles of the man(7) and ms(7) macro sets.  One of
  7. cawf's virtues is that it will run on PC clones under MS-DOS.  It is
  8. also, like awf, totally independent of any licensed Unix source code.
  9.  
  10. This is the second distribution of cawf.  Changes include:
  11.  
  12.     o  Support has been added for a few more nroff commands -- .di, .tr,
  13.        and \k.
  14.  
  15.     o  Known bugs have been corrected, including bugs in the man.mac
  16.        and ms.mac files:
  17.  
  18.         Error in skipping to predicate of argument string comparison
  19.         .if;
  20.  
  21.         Improved .ti handling, including the undocumented, oft-used
  22.         absolute form;
  23.  
  24.         Error in output of .NH numbers;
  25.  
  26.         Handle expressions that aren't separated from the command by
  27.         white space -- e. g., ".ti0";
  28.  
  29.         Compensate for printers that can't print a blank line,
  30.         followed by a FF without printing a blank page.
  31.  
  32.     o  A limited printer formatting capability has been added via a small
  33.        change to cawf (the -fe option) and the addition of a post-filter,
  34.        fontfilt(1).
  35.  
  36.     o  Documentation has been added to describe the additions.
  37.  
  38.  
  39. CONTENTS
  40. --------
  41.  
  42. This distribution of cawf includes:
  43.  
  44.     *.c and *.h    source files to build cawf, bsfilt (bsfilt
  45.             removes Backspaces from cawf output) and
  46.             fontfilt (fontfilt provides more elaborate
  47.             font and type style filtering)
  48.     bsfilt.1    nroff source for the bsfilt manual page
  49.     bsfilt.exe    bsfilt executable for MS-DOS
  50.     bsfilt.man    the formatted (with cawf -fn) bsfilt manual page
  51.     cawf.1        nroff source for the cawf manual page
  52.     cawf.exe    cawf executable for MS-DOS
  53.     cawf.mak    MS-DOS, Quick-C make file for cawf
  54.     cawf.man    the formatted (with cawf -fn) cawf manual page
  55.     common        initialization file for CAWFLIB library
  56.     dumb.dev    device description file for CAWFLIB library
  57.     fontfilt.1    nroff source for the fontfilt manual page
  58.     fontfilt.cf    device and font configuration file for fontfilt(1)
  59.     fontfilt.exe    fontfilt executable for MS-DOS
  60.     fontfilt.mak    MS-DOS Quick-C make file for fontfilt
  61.     fontfilt.man    the formatted (with cawf -fn) fontfilt manual page
  62.     makefile    Unix-style make file
  63.     man.mac        man(7) macros for CAWFLIB library
  64.     ms.mac        ms(7) macros for CAWFLIB library
  65.  
  66.  
  67. LIBRARY
  68. -------
  69.  
  70. To use cawf, you must select a location for the CAWFLIB library files.  The
  71. distributed cawf.exe expects to find them in c:\sys\lib\cawf, but you can
  72. alter that with the CAWFLIB environment variable, or you can change the
  73. CAWFLIB #define in cawf.h and rebuild cawf from the sources.
  74.  
  75. CAWFLIB contains a minimum of five files:
  76.  
  77.     common        common raw nroff commands to get cawf started
  78.     dumb.dev    a basic set of definitions for a plain, "dumb"
  79.             output device - e. g., the console display or
  80.             a generic line printer
  81.     fontfilt.cf    the device and font configuration file for
  82.             fontfilt(1)
  83.     man.mac        the man(7) macros
  84.     ms.mac        the ms(7) macros
  85.  
  86. You may want to add your own macro files to the library.  Just name them
  87. "m[your-name].mac", following the usual nroff naming convention for macro
  88. files.
  89.  
  90. If you have fancy output devices, you may want to generate new *.dev files
  91. for them.  Follow the format of dumb.dev.  To define support for a new
  92. device, select a name prefix for it and create a file in CAWFLIB with the
  93. name "<prefix>.dev".  To use the new device file, set the TERM environment
  94. variable to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev,
  95. because my TERM environment variable value is usually vt100.  (All I need
  96. do is make vt100.dev a symbolic link to dumb.dev.)
  97.  
  98. Through its -fe option and the fontfilt(1) post-filter cawf provides
  99. limited support for printer devices.  Cawf and fontfilt can be directed
  100. to issue specific printer codes for bold and italic characters, and one
  101. font can be selected for the entire document.  A device and font
  102. configuration file is used for these selections, and the file can be
  103. easily changed for individual printers.
  104.  
  105.  
  106. SOURCES
  107. -------
  108.  
  109. A generic Unix make file and a cawf.mak file for version 2.5 of Microsoft
  110. MS-DOS Quick-C are included.  The Unix make file has some definitions that
  111. help tune it to the local Unix environment:
  112.  
  113.     CAWFLIB        is a string that can be used in lieu of changes
  114.             to cawf.h's CWFLIB #define.
  115.  
  116.     UNIX        switches the build environment to Unix.
  117.  
  118.     USG        adjusts for System V.  (UNIX must also be defined.)
  119.  
  120.     STDLIB        indicates that standard library function prototype
  121.             definitions may be found in <stddef.h>.
  122.  
  123.             If STDLIB is not defined, the cawf sources try to
  124.             define their own library function return values.
  125.  
  126. Cawf has been successfully built and tested in the UNIX context under 4.3BSD
  127. Tahoe, Ultrix 2.2, SunOS 4.0, Dynix 3.0.12, ETAV (a SYSV 3.2 derivative) and
  128. NeXTStep 1.0a/2.0.  If you try to build under a BSD derivative Unix that
  129. doesn't have the SYSV string functions, strchr() and strrchr(), simply
  130. redefine them to the index() and rindex() functions.
  131.  
  132.  
  133. MS-DOS CONSIDERATIONS
  134. ---------------------
  135.  
  136. The MS-DOS version of cawf was created to run under the KornShell of the
  137. Mortis Kern Systems Toolkit.  One ramification of using MKS' ksh is that it
  138. supports the separate standard error and standard output streams.  Hence,
  139. cawf blithely distributes its error messages to the standard error file, and
  140. assumes the user's shell is capable of separating them from standard output.
  141.  
  142. If you don't use the MKS KornShell, but do want to separate the output
  143. streams, you'll have to modify the cawf source code.  As a rudimentary aid,
  144. cawf uses a separate stream pointer, Efs, for writing error output, but sets
  145. it to stderr.  You can change that process to open a separate error file and
  146. set Efs to point to it.
  147.  
  148.  
  149. COPYRIGHTS AND CREDITS
  150. ----------------------
  151.  
  152. The sources are copyrighted, but freely distributable under usual terms -
  153. retention of credit, etc.
  154.  
  155. Please acknowledge:
  156.  
  157.     AT&T for their public-domain release of getopt(3) at the 1985
  158.     UNIFORUM conference
  159.  
  160.     Chet Creider and Ted Campbell for their contributions to font
  161.     filtering
  162.  
  163.     Henry Spencer for awf and his regular expression package
  164.  
  165. Henry says about awf, "I can't believe I really wrote this."  Those are
  166. my sentiments exactly about cawf, but I also understand that necessity
  167. sometimes forces us to do what we would prefer to avoid.
  168.  
  169.  
  170. BUGS AND ENHANCEMENTS
  171. ---------------------
  172.  
  173. I'll be glad to hear about bugs and needs for enhancements, but make no
  174. promises about delivering fixes or upgrades in response.
  175.  
  176. Vic Abell <abe@mace.cc.purdue.edu>
  177. 4 June 1991
  178.